home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 43 / Amiga Format CD43 (1999)(Future Publishing)(GB)(Track 1 of 2)[!][issue 1999-09].iso / -serious- / programming / other / mysticlib / doc / autodoc / mysticview.doc < prev    next >
Text File  |  1999-06-14  |  18KB  |  510 lines
  1. TABLE OF CONTENTS
  2.  
  3. mysticview.library/MV_CreateA
  4. mysticview.library/MV_DrawOff
  5. mysticview.library/MV_DrawOn
  6. mysticview.library/MV_Delete
  7. mysticview.library/MV_GetAttrsA
  8. mysticview.library/MV_Refresh
  9. mysticview.library/MV_SetAttrsA
  10. mysticview.library/MV_SetViewRelative
  11. mysticview.library/MV_SetViewStart
  12. mysticview.library/MV_CreateA                   mysticview.library/MV_CreateA
  13.  
  14.     NAME
  15.         MV_CreateA  - create a mysticview instance.
  16.         MV_Create   - varargs stub for MV_CreateA.
  17.  
  18.     SYNOPSIS
  19.         mysticview = MV_CreateA(screen,rastport,taglist)
  20.         d0                      a0     a1       a2
  21.  
  22.         APTR MV_CreateA(struct Screen *,struct RastPort *,struct TagItem *)
  23.  
  24.         APTR MV_Create(struct Screen *,struct RastPort *,...,TAG_DONE)
  25.  
  26.     FUNCTION
  27.         This function creates a viewer instance for a given screen and
  28.         rastport.
  29.  
  30.     INPUTS
  31.         screen      - pointer to the Screen for the viewer to appear on.
  32.         rastport    - pointer to the RastPort for the viewer to appear on.
  33.         tags        - pointer to an array of TagItems. most of these
  34.                       attributes are both available to this function and
  35.                       to MV_SetAttrsA(). there are only few attributes that
  36.                       can only be passed to MV_CreateA() for initialization:
  37.  
  38.     TAGS
  39.         MVIEW_Priority (ULONG) - task priority for the viewer's background
  40.                 task. valid range: -128...127. do not set this priority
  41.                 unless you have a good reason to and know exactly what you
  42.                 are doing, and better do not set this priority above your
  43.                 own task's priority.
  44.                 default: the caller's task priority.
  45.  
  46.         MVIEW_RPSemaphore (struct SignalSemaphore *) - pointer to
  47.                 an initialized SignalSemaphore, being obtained for
  48.                 each access to the view's underlying RastPort.
  49.                 locking the RastPort is mandatory if you want to
  50.                 share it between tasks, so you MUST supply this tag
  51.                 if you want to draw ANYTHING to the same RastPort
  52.                 as the view's background task. (v4) example:
  53.                 
  54.                 struct SignalSemaphore rastlock;
  55.                 InitSemaphore(&rastlock);
  56.  
  57.                 mview = MV_Create(screen, rastport, 
  58.                    MVIEW_RPSemaphore, &rastlock, ...);
  59.                 
  60.                 MV_DrawOn(mview);
  61.                 
  62.                 ...
  63.                 
  64.                 /* your drawing here: */
  65.                 
  66.                 ObtainSemaphore(&rastlock);
  67.                 
  68.                 SetAPen(rastport, pen);
  69.                 Move(rastport, ...);
  70.                 Draw(rastport, ...);
  71.                 
  72.                 ReleaseSemaphore(&rastlock);
  73.                 
  74.                 ...
  75.                 
  76.                 MV_Delete(mview);
  77.                 
  78.                 note: the view's background task tries to hold
  79.                 locks on the semaphore as short as possible, and
  80.                 it frees the lock as often as possible, even for
  81.                 very short time spans. try to be as fair as the
  82.                 view.
  83.  
  84.     RESULTS
  85.         mysticview - the mysticview instance created, or NULL if
  86.                      something went wrong.
  87.                      
  88.     NOTES
  89.         only the tags that are exclusively available to MV_CreateA()
  90.         are listed here. refer to the documentation of MV_SetAttrsA()
  91.         for all other tags.
  92.  
  93.     SEE ALSO
  94.         MV_Delete(), MV_DrawOn()
  95.  
  96. mysticview.library/MV_DrawOff                   mysticview.library/MV_DrawOff
  97.  
  98.     NAME
  99.         MV_DrawOff - disable asynchronous drawing.
  100.  
  101.     SYNOPSIS
  102.         MV_DrawOff(mysticview)
  103.                   a0
  104.  
  105.         void MV_DrawOff(APTR)
  106.  
  107.     FUNCTION
  108.         This function turns off asynchronous drawing for the given
  109.         mysticview instance.
  110.  
  111.     INPUTS
  112.         mysticview  - pointer to a mysticview instance.
  113.  
  114.     RESULTS
  115.         none
  116.  
  117.     SEE ALSO
  118.         MV_DrawOn()
  119.  
  120. mysticview.library/MV_DrawOn                     mysticview.library/MV_DrawOn
  121.  
  122.     NAME
  123.         MV_DrawOn - enable asynchronous drawing.
  124.  
  125.     SYNOPSIS
  126.         success = MV_DrawOn(mysticview)
  127.         d0                  a0
  128.  
  129.         BOOL MV_DrawOn(APTR)
  130.  
  131.     FUNCTION
  132.         This function will establish a background task for the given
  133.         mysticview instance. it will perform asynchronous drawing and
  134.         instantly react to changes of attributes.
  135.  
  136.     INPUTS
  137.         mysticview  - pointer to a mysticview instance.
  138.     
  139.     RESULTS
  140.         success - boolean to indicate whether background drawing
  141.                   could be established.
  142.  
  143.     SEE ALSO
  144.         MV_DrawOff(), MV_SetAttrsA()
  145.  
  146. mysticview.library/MV_Delete                     mysticview.library/MV_Delete
  147.  
  148.     NAME
  149.         MV_Delete - destroy a mysticview instance.
  150.  
  151.     SYNOPSIS
  152.         MV_Delete(mysticview)
  153.                   a0
  154.  
  155.         void MV_Delete(APTR)
  156.  
  157.     FUNCTION
  158.         This function will delete a mysticview instance, shut down
  159.         related tasks and free all associated memory.
  160.  
  161.     INPUTS
  162.         mysticview  - pointer to a mysticview instance.
  163.  
  164.     RESULTS
  165.         none
  166.     
  167.     NOTES
  168.         You must delete a mysticview instance before you may close
  169.         the underlying Screen or Window.
  170.  
  171.     SEE ALSO
  172.         MV_CreateA()
  173.  
  174. mysticview.library/MV_GetAttrsA               mysticview.library/MV_GetAttrsA
  175.  
  176.     NAME
  177.         MV_GetAttrsA - query attributes.
  178.         MV_GetAttrs  - varargs stub for MV_GetAttrsA.
  179.  
  180.     SYNOPSIS
  181.         MV_GetAttrsA(mysticview,taglist)
  182.                      a0         a1
  183.  
  184.         void MV_GetAttrsA(APTR,struct TagItem *)
  185.  
  186.         void MV_GetAttrsA(APTR,...,TAG_DONE)
  187.  
  188.     FUNCTION
  189.         Retrieve a list of attributes from a mysticview instance.
  190.  
  191.     INPUTS
  192.         mysticview  - pointer to a mysticview instance.
  193.         tags        - pointer to an array of TagItems.
  194.  
  195.     TAGS
  196.         refer to the attributes' descriptions in MV_SetAttrsA().
  197.         additional tags that may be queried only:
  198.         
  199.         MVIEW_PictureHeight (ULONG *) - current visible
  200.                 height of the picture inside the RastPort.
  201.  
  202.         MVIEW_PictureWidth (ULONG *) - current visible width
  203.                 of the picture inside the RastPort.
  204.  
  205.         MVIEW_PictureX (ULONG *) - current left edge of the
  206.                 picture inside the RastPort.
  207.  
  208.         MVIEW_PictureY (ULONG *) - current top edge of
  209.                 the picture inside the RastPort.
  210.  
  211.     RESULTS
  212.         none
  213.         
  214.     NOTES
  215.         the tags that are exclusively available to MV_CreateA() cannot
  216.         be queried with this function.
  217.         
  218.     SEE ALSO
  219.         MV_CreateA(), MV_SetAttrsA()
  220.  
  221. mysticview.library/MV_Refresh                   mysticview.library/MV_Refresh
  222.  
  223.     NAME
  224.         MV_Refresh - refresh the display.
  225.  
  226.     SYNOPSIS
  227.         MV_Refresh(mysticview)
  228.                    a0
  229.  
  230.         void MV_Refresh(APTR)
  231.  
  232.     FUNCTION
  233.         This function will refresh the mysticview's current display,
  234.         reflecting all changes that applied meanwhile, and redraw the
  235.         picture. this function might be of use when you perform changes
  236.         inside the picture's raw data, or when your RastPort's window
  237.         is of the type WFLG_SIMPLE_REFRESH and you need to signal the
  238.         viewer to redraw the picture, or when you do not use asynchronous
  239.         drawing.
  240.  
  241.     INPUTS
  242.         mysticview  - pointer to a mysticview instance.
  243.  
  244.     RESULTS
  245.         none
  246.  
  247.     SEE ALSO
  248.         MV_DrawOn(), MV_SetAttrsA()
  249.  
  250. mysticview.library/MV_SetAttrsA               mysticview.library/MV_SetAttrsA
  251.  
  252.     NAME
  253.         MV_SetAttrsA - set attributes.
  254.         MV_SetAttrs  - varargs stub for MV_SetAttrsA.
  255.  
  256.     SYNOPSIS
  257.         MV_SetAttrsA(mysticview,taglist)
  258.                      a0         a1
  259.  
  260.         void MV_SetAttrsA(APTR,struct TagItem *)
  261.  
  262.         void MV_SetAttrsA(APTR,...,TAG_DONE)
  263.  
  264.     FUNCTION
  265.         submit a list of attributes to a mysticview instance.
  266.         any changes will be applied instantly when background
  267.         drawing has been activated via MV_DrawOn().
  268.  
  269.     INPUTS
  270.         mysticview  - pointer to a mysticview instance.
  271.         tags        - pointer to an array of TagItems.
  272.  
  273.     TAGS
  274.         MVIEW_BackColor (ULONG) - RGB background color for areas not
  275.                 covered by the image. default: a pale, dark green
  276.                 
  277.         MVIEW_DestHeight (ULONG) - destination height inside the RastPort.
  278.                 default: undefined.
  279.  
  280.         MVIEW_DestWidth (ULONG) - destination width inside the RastPort.
  281.                 default: undefined.
  282.  
  283.         MVIEW_DestX (ULONG) - destination left edge inside the RastPort.
  284.                 default: undefined.
  285.  
  286.         MVIEW_DestY (ULONG) - destination top edge inside the RastPort.
  287.                 default: undefined.
  288.  
  289.         MVIEW_DisplayMode (ULONG) - image scaling and aspect mode.
  290.                 currently defined:
  291.                
  292.                 MVDISPMODE_FIT
  293.                      the image fits exactly into the visible area and
  294.                      may get distorted.
  295.  
  296.                 MVDISPMODE_KEEPASPECT_MIN
  297.                       respect the aspect ratios of both the screen and
  298.                       the picture. the image is fully visible at zoom
  299.                       factor 1.
  300.  
  301.                 MVDISPMODE_KEEPASPECT_MAX
  302.                       respect the aspect ratios of both the screen and
  303.                       the picture. either the image's width or height is
  304.                       fully visible at zoom factor 1.
  305.  
  306.                 MVDISPMODE_ONEPIXEL
  307.                       ignore the image aspect. the screen's aspect will
  308.                       be respected, though.                
  309.  
  310.                 MVDISPMODE_IGNOREASPECT
  311.                       ignore both the screen's and image's aspects.
  312.                 
  313.                 default: MVDISPMOVE_KEEPASPECT_MIN
  314.  
  315.         MVIEW_Dither (ULONG) - dither activation mode on displays with
  316.                 256 colors (or less), or on HAM displays.
  317.                 
  318.                 MVDITHERMODE_ON   - always dither
  319.                 
  320.                 MVDITHERMODE_OFF  - never dither
  321.                 
  322.                 MVDITHERMODE_AUTO - dither only when necessary. refer
  323.                       to the 'prefs' textfile in the guigfx.library
  324.                       distribution, guigfx.library/DrawPictureA() and
  325.                       render.library/RGBArrayDiversityA() for details.
  326.                 
  327.                 default: MVDITHERMODE_AUTO
  328.  
  329.         MVIEW_DitherMode (ULONG) - error diffusion mode. refer to
  330.                 render/render.h for the available modes.
  331.                 default: DITHERMODE_EDD.
  332.  
  333.         MVIEW_HSType (ULONG) - histogram type, according to the
  334.                 definitions in render/render.h. do not touch unless
  335.                 you know exactly what you are doing. only _TURBO types
  336.                 are allowed. default: HSTYPE_12BIT_TURBO
  337.  
  338.         MVIEW_Picture (APTR) - pointer to a guigfx.library picture to
  339.                 be displayed. the image is NOT incorporated to the 
  340.                 mysticview instance, it is only referenced. the image
  341.                 MUST NOT be deleted when it is the current picture of
  342.                 a mysticview instance. delete the viewer first, or set
  343.                 MVIEW_PICTURE to NULL before. default: NULL
  344.  
  345.         MVIEW_Precision (ULONG) - color allocation precision. refer to
  346.                 graphics.library/ObtainBestPenA().
  347.                 default: PRECISION_ICON
  348.  
  349.         MVIEW_PreviewMode (ULONG) - realtime refresh mode.
  350.                 
  351.                 MVPREVMODE_NONE
  352.                       no realtime refresh takes place.
  353.  
  354.                 MVPREVMODE_GRID
  355.                       when the image scrolls, scales or rotates, or 
  356.                       when the visible dimensions change, the image
  357.                       is first drawn as a grid, and then rendered with
  358.                       highest quality.
  359.  
  360.                 MVPREVMODE_OPAQUE
  361.                       when the image scrolls, scales or rotates, or 
  362.                       when the visible dimensions change, the entire
  363.                       image is first drawn as a quick and dirty
  364.                       preview, and then rendered with highest quality.
  365.  
  366.                 default: MVPREVMODE_NONE
  367.  
  368.         MVIEW_ReadySignal (ULONG) - signal bit that will be submitted
  369.                 to your task when the current picture has been completely
  370.                 rendered in highest quality. default: -1 (no signal will
  371.                 be submitted)
  372.  
  373.         MVIEW_Rotation (ULONG)
  374.                 rotation of the image as a fixed floatpoint integer.
  375.                 the upper 16 bit determine the integral part of the
  376.                 number, the lower 16 bit determine the fraction. valid
  377.                 range is 0 (0°) to 1 (360°). defaults to 0.
  378.  
  379.         MVIEW_ScreenAspectX (ULONG)
  380.         MVIEW_ScreenAspectY (ULONG)
  381.                 enforce a screen aspect.
  382.                 default: the screen's aspect.
  383.  
  384.         MVIEW_ShowCursor (BOOL)
  385.                 display an image cursor. default: FALSE
  386.  
  387.         MVIEW_StaticPalette (BOOL)
  388.                 use the same static palette for any picture instead of a
  389.                 dynamic one. this will result in a faster display at
  390.                 lower quality. skipping from one picture to another
  391.                 causes less flickering with a static palette.
  392.                 default: FALSE (dynamic palettes are used)
  393.  
  394.         MVIEW_Text (char *) - a single line of text to be displayed
  395.                 at the bottom of the picture's area inside the RastPort.
  396.                 the text will be copied to the mysticview instance and
  397.                 may be freed prior to the mysticview instance.
  398.                 default: NULL
  399.  
  400.         MVIEW_XPos (ULONG)
  401.         MVIEW_YPos (ULONG)
  402.                 horizontal/vertical position inside the image. this is a
  403.                 fixed-floatpoint integer. the upper 16 bit determine the
  404.                 integral part of the number, the lower 16 bit determine the
  405.                 fraction. valid range is from 0 to 1.
  406.                 default is 0.5 (0x00008000)
  407.  
  408.         MVIEW_Zoom (ULONG) - zoom factor. this is a fixed-floatpoint
  409.                 integer. the upper 16 bit determine the integral part
  410.                 of the number, the lower 16 bit determine the fraction.
  411.                 valid range is from 0.1 to 10. default is 1 (0x00010000)
  412.         
  413.         MVIEW_DrawArrows (ULONG) - boolean to indicate that small
  414.                 arrows are to be drawn to the view's borders, when a
  415.                 picture is not fully visible. default: FALSE (v4)
  416.         
  417.         MVIEW_ShowPip (ULONG) - boolean to indicate that a PiP
  418.                 view of the current picture is to be displayed.
  419.                 this feature is considered experimental (v4).
  420.                 better do not use it. default: FALSE (v4)
  421.         
  422.         MVIEW_TextColor (ULONG) - 0x00rrggbb value for displaying
  423.                 text (see MVIEW_Text attribute). default: white.
  424.                 (v4)
  425.         
  426.         MVIEW_MarkColor (ULONG) - 0x00rrggbb value for displaying
  427.                 highlighted display elements, such as arrows, grid
  428.                 lines and the PiP frame. defaut: bright green.
  429.                 (v4)
  430.         
  431.     RESULTS
  432.         none
  433.  
  434.     NOTES
  435.         all these attributes are also available to MV_CreateA().
  436.  
  437.     SEE ALSO
  438.         MV_CreateA(), MV_GetAttrsA(), MV_DrawOn(), MV_Refresh()
  439.  
  440. mysticview.library/MV_SetViewRelative   mysticview.library/MV_SetViewRelative
  441.  
  442.     NAME
  443.         MV_SetViewRelative - perform relative movement of the picture
  444.  
  445.     SYNOPSIS
  446.         MV_SetViewRelative(mysticview,newx,newy)
  447.                            a0         d0   d1
  448.  
  449.         void MV_SetViewRelative(APTR,LONG,LONG)
  450.  
  451.     FUNCTION
  452.         This function performs a relative movement of the mysticview's
  453.         current picture.
  454.         
  455.         in this example, we assume that you want to allow the user to
  456.         drag the picture around with the mouse. proceed as follows:
  457.         
  458.         - on a MOUSEBUTTON / SELECTDOWN event, call MV_SetViewStart()
  459.           with the mouse coordinates related to this event. call
  460.           ModifyIDCMP() to catch MOUSEMOVE events now.
  461.         
  462.         - while dragging (thus, by receiving MOUSEMOVE events), pass
  463.           the mouse coordinates to the mysticview instance via
  464.           MV_SetViewRelative(). this will position the visible part
  465.           of the picture. attributes like zoom, displaymode, rotation,
  466.           aspects, etc. are fully considered.
  467.         
  468.         - when receiving a MOUSEBUTTON / SELECTUP event, call
  469.           ModifyIDCMP() and disable MOUSEMOVE events. (There is no
  470.           need for your application to be burdened with a continous
  471.           flood of mouse movement events.)
  472.  
  473.     INPUTS
  474.         mysticview  - pointer to a mysticview instance.
  475.         newx        - new x coordinate
  476.         newy        - new y coordinate
  477.  
  478.     RESULTS
  479.         none
  480.  
  481.     SEE ALSO
  482.         MV_SetViewStart()
  483.  
  484. mysticview.library/MV_SetViewStart         mysticview.library/MV_SetViewStart
  485.  
  486.     NAME
  487.         MV_SetViewStart - set starting point for picture movement
  488.  
  489.     SYNOPSIS
  490.         MV_SetViewStart(mysticview,startxpos,startypos)
  491.                         a0         d0        d1
  492.  
  493.         void MV_SetViewStart(APTR,LONG,LONG)
  494.  
  495.     FUNCTION
  496.         This function sets that starting coordinate for
  497.         a relative movement of the picture inside the RastPort.
  498.         Refer to MV_SetViewRelative() for further details.
  499.  
  500.     INPUTS
  501.         mysticview  - pointer to a mysticview instance.
  502.         startxpos   - initial x coordinate
  503.         startypos   - initial y coordinate
  504.  
  505.     RESULTS
  506.         none
  507.  
  508.     SEE ALSO
  509.         MV_SetViewRelative()
  510.